---
title: TLS
subtitle: Secure client-side and subgraph-side communications
redirectFrom: 
  - /router/configuration/overview/#tls
---

The GraphOS Router supports TLS to authenticate and encrypt communications, both on the client side and the subgraph side. It works automatically on the subgraph side if the subgraph URL starts with `https://`.

```yaml title="Example TLS configuration"
tls:
  supergraph:
    certificate: ${file./path/to/certificate.pem}
    certificate_chain: ${file./path/to/certificate_chain.pem}
    key: ${file./path/to/key.pem}
```

## Configuring TLS

TLS support is configured in the `tls` section, under the `supergraph` key for the client side, and the `subgraph` key for the subgraph side, with configuration possible for all subgraphs and overriding per subgraph.

The list of supported TLS versions and algorithms is static.

### Supported TLS versions 

* TLS 1.2
* TLS 1.3

### Supported TLS cipher suites

* TLS13_AES_256_GCM_SHA384
* TLS13_AES_128_GCM_SHA256
* TLS13_CHACHA20_POLY1305_SHA256
* TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
* TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
* TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
* TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
* TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
* TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256

### Supported key exchange groups

* X25519
* SECP256R1
* SECP384R1

## TLS termination

Clients can connect to the router directly over HTTPS, without terminating TLS in an intermediary. You can configure this in the `tls` configuration section:

```yaml
tls:
  supergraph:
    certificate: ${file./path/to/certificate.pem}
    certificate_chain: ${file./path/to/certificate_chain.pem}
    key: ${file./path/to/key.pem}
```

To set the file paths in your configuration with Unix-style expansion, you can follow the examples in the [variable expansion](#variable-expansion) guide. 

The router expects the file referenced in the `certificate_chain` value to be a combination of several PEM certificates concatenated together into a single file (as is commonplace with Apache TLS configuration).

## Overriding certificate authorities for subgraphs

The router verifies TLS connections to subgraphs using the list of certificate authorities the system provides. You can override this list with a combination of global and per-subgraph settings:

```yaml
tls:
  subgraph:
    # Use these certificate authorities unless overridden per-subgraph
    all:
      certificate_authorities: "${file./path/to/ca.crt}"
    # Override global setting for individual subgraphs
    subgraphs:
      products:
        certificate_authorities: "${file./path/to/product_ca.crt}"
```

The router expects the file referenced in the `certificate_chain` value to be a combination of several PEM certificates concatenated together into a single file (as is commonplace with Apache TLS configuration).

You can only configure these certificates via the router's configuration since using `SSL_CERT_FILE` also overrides certificates for sending telemetry and communicating with Apollo Uplink.

If the subgraph is presenting a self-signed certificate, it must be generated with the proper file extension and with `basicConstraints` turned off. You can generate it with the following command line command from a certificate signing request, in this example, `server.csr`:

```
openssl x509 -req -in server.csr -signkey server.key -out server.crt -extfile v3.ext
```

You can generate a `v3.ext` extension file like so:

```
subjectKeyIdentifier   = hash
authorityKeyIdentifier = keyid:always,issuer:always
# this has to be turned off
# basicConstraints       = CA:TRUE
keyUsage               = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign
subjectAltName         = DNS:local.apollo.dev
issuerAltName          = issuer:copy
```

<Note>

Make sure to change the `subjectAltName` field to the subgraph's name.

</Note>

This produces the file as `server.crt` which can be used in `certificate_authorities`.

## TLS client authentication for subgraph requests

The router supports mutual TLS authentication (mTLS) with the subgraphs. This means that it can authenticate itself to the subgraph using a certificate chain and a cryptographic key. It can be configured as follows:

```yaml
tls:
  subgraph:
    # Use these certificates and key unless overridden per-subgraph
    all:
      client_authentication:
        certificate_chain: ${file./path/to/certificate_chain.pem}
        key: ${file./path/to/key.pem}
    # Override global setting for individual subgraphs
    subgraphs:
      products:
        client_authentication:
          certificate_chain: ${file./path/to/certificate_chain.pem}
          key: ${file./path/to/key.pem}
```

## Redis TLS configuration

For Redis TLS connections, you can set up a client certificate or override the root certificate authority by configuring `tls` in your router's [YAML config file](https://www.apollographql.com/docs/router/overview/#yaml-config-file). For example:

```yaml
apq:
  router:
    cache:
      redis:
        urls: [ "rediss://redis.example.com:6379" ]
        #highlight-start
        tls:
          certificate_authorities: ${file./path/to/ca.crt}
          client_authentication:
            certificate_chain: ${file./path/to/certificate_chain.pem}
            key: ${file./path/to/key.pem}
        #highlight-end
```
